package org.xx.armory.db;

import java.util.Set;

/**
 * 表示数据库事务的操作。
 *
 * @author Haart
 */
public interface Transaction
        extends AutoCloseable {
    /**
     * 登记一个事务的使用者。
     * <p>通过登记使用者，事务自身可以了解当前正在使用该事务的对象</p>
     *
     * @param user
     *         事务的使用者。
     * @return 数据库连接引用。
     * @throws IllegalArgumentException
     *         如果参数{@code user}是{@code null}。
     */
    ConnectionRef enroll(
            Object user
    );

    /**
     * 撤销事务的使用者。
     *
     * @param user
     *         事务的使用者。
     * @throws IllegalArgumentException
     *         如果参数{@code user}是{@code null}。
     */
    void revoke(
            Object user
    );

    /**
     * 获取事务的使用者集合。
     *
     * @return 事务的使用者集合。
     */
    Set<Object> getUsers();

    /**
     * 设置数据脏标志。
     */
    void setDirty();

    /**
     * 提交数据库事务，同时清除数据脏标志。
     * <p>如果数据脏标志尚未设置，可以不执行任何操作。</p>
     *
     * @throws DbException
     *         如果出现数据库访问错误。
     */
    void commit();

    /**
     * 回滚数据库事务，同事清除数据脏标志。
     * <p>如果数据脏标志尚未设置，可以不执行任何操作。</p>
     *
     * @throws DbException
     *         如果出现数据库访问错误。
     */
    void rollback();

    /**
     * 判断事务是否可用。
     * @return 事务是否可用。
     */
    boolean isActive();
}
